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Abstract 

We present here an installation guide, a hand-on mini-tutorial through 
examples, and the theoretical foundations of the Hilbert++ code. 

1 INSTALLATION 

The code is provided in both souce and binary forms. The binaries are meant to 
run under the Linux-i386 system. The distribution package is composed of two 
archives. The first one (let's call it installation archive) which provides all the 
necessary libraries that Hilbert++ needs, and a second one, Hilbert+H- itself, 
which comprises sources, binaries, and examples. 

HilbertH — h loads dynamically the libraries of the installation archive and 
does not depend on which Linux-packages are installed on your system with the 
exception of libc and libXll. As these libraries are quite stable one should be 
able to run HilbertH — h on any Linux system without recompiling it. 

The current installation archive and the Hilbert+H- packages can be retrieved 
fro m these addresses : \kttp://ftp. esrf.fr/pub/sciso ft/ESRF_sw/scisoft-ESRF_swJinuxi386-03.tar.gz 
and http://ftp.esrf.fr/pub/scisoft/ESRF_sw/linux_i386_03/hilbertxx.tar.gz respec- 
tively. 

The installation archive must be untarred using the following commands 
cd / 

tar -xzvf yourdownloaddirectory/scisof t_ESRF_sw_linuxi386_03 .tar . gz 

this creates the directory /scisoft/ESRF_sw/linuxJ386_03/. 

The hilbertxx directory can be untarred from any directory with the com- 
mand : 

cd <whereever> 

tar -xzvf yourdownloaddirectory/hilbertxx.tar .gz 



2 Hand on mini-tutorial by examples 

To launch the program you go to hilbertxx/examples/exa_c/ass, where class 
corresponds to an example class. The example classes provided so far are : 
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Ex. a) class=2p3d for L2-L3 spectroscopy 

Ex. b) class=vhis for ls-3p RIXS spectroscopy, with a 3d resonant intermediate 
state, in transition metal oxides. 

Ex. c) class=df for dipolar d to f transitions. 

You choose an example system by moving to one of the subdirectories. For 
instance 

cd hilbertxx/ examples/exa_2p3d/Mn3+/ 

Once you are in the ex&_class/ system directory you start the application by 
running the Python script : 

. . /runthisscript 

You get a command line prompt: 

>>> 

and you can get some help by typing 
>»help() 

The help function prints some brief instructions for every Hilbert++-command 
( hxx- command ) . A hxx-command is always one line long and writing it does 
not require any knowledge of Python. The advanced user can write Python 
scripts. We explain for each example the available commands 

2.1 The 2p3d examples class 
2.1.1 Mn3+ 

cd to the appropriate directory 

cd hilbertxx/ examples/exa_2p3d/Mn3+/ 

and start the script 

. ./runthisscript 

You get now a Python prompt. You can type several commands. In this 
manual we are going to explain all the commands. The command help() which 
produces the following list of available commands : 

AVAILABLE HXX-COMMANDS ( examples of ) 
set (system) # or use directly python syntax to change the attributes of object system. 

# When using the set (system) function you can also give a filename of a previously 

# saved ( and edited ) file 

save(system) # You are asked a filename and you have to quote it like "filename" 

scriviFiles(5,pref ix="datas" , nhopped=0) # To generate matrices files. This command creates the Hilbert space 

# and writes the terms composing the Hamiltonian into (sub) directory "datas" which must exist. 

# The above example generates a Hilbert space where 5 electrons are distributed in the 3d 
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# shell in all possible combinations. 

# Giving nhopped=n as argument, besides the configurations with 5 electrons on 3d also the configurations 

# with 5+i electrons on 3d and 10-i on Ligands orbitals are considered ( 0<=i<=nhopped ) 

system. case="datas" # This chooses the system that you have expanded with scriviFiles command. 

# You can acces this property also with the set (system) command 

res=system.GetSpectrum() # to calculate a spectrum, res is a list.res[0] is an array of floats : the energies. 

# res [i>=l] are the resonances ( real and imaginary part). Dipolar transitions are calculated as 

# res[i], where i=l,2,3 and Mz= -1,0,1 

res=system.GetSpectrum( [ fml,f0,fl ]) # Absorption (it is res[l].imag) for a definite polarisation. 

# Fml,f0,fl are three coefficients. 

# They can be complex. So you can define any polarisation : 

# For Z polarisation [ fml,f0,fl ] = [ 0, 1, 0] 

# For X polarisation [ fml,f0,fl ] = [-1/sqrt (2 . 0) , , 1/sqrt (2 . 0)] 

# For Y polarisation [ fml,f0,fl ] = [ l.Oj /sqrt(2.0) , , 1 .0j/sqrt(2.0)] 

# and so on 



write (res , filename) # To save res on a file 

# and the file will have several columns ( 1 for energies and two (real, imag) for each polarisation) 

Plot (Curve (res [0] , res [n>=l] . imag, Pen(Red), "legend")) # To plot. Change n to select the polarisation that you want 

# The plotting feature uses qt , iqt and qwt . If you run a long job in the background you must 

# desactivate this graphics feature by commenting out, in the file init.py, the lines where such packages 

# are imported 

Es , S2s, L2s, SL2, occPs , Szs, Lzs= system. GetESLcounters () # to get statistics: a list of E, the list of 3d L2 , 

# the list of 3d S2, the list of 3d SL, a list of ligand expected occupation, a list of 3d Sz expectation 



The system is represented by the Python variable system. Such a variable 
is an object and its properties are the parameters. There are several ways to 
change such properties. One is to use the set(system) command. This command 
prints the list of parameters : 



>>> 


set (system) 








BASE 


HAMILTONIAN 






1) 


base 


_couchel_F0 




5.0 


2) 


base 


_couchel_F2 




12.4156828106 


3) 


base 


_couchel_F4 




7.81967819912 


4) 


base 


_couche0_l_F0 


5.5 


5) 


base 


_coucheO_l_F2 


6.86721502072 


6) 


base 


_couche0_l_Gl 


5.02109490016 


7) 


base 


_coucheO_l_G3 


2.85321756768 


8) 


base 


_so_o 




6.568603656 


9) 


base 


_S0_1 




0.05238772 


10) 


base 


_Sop_Zero 




le-05 


11) 


base 


_Sop_Minus 




0.0 


12) 


base 


_Sop_Plus 




0.0 


13) 


base 


.counterDL 
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EXCITED HAMILTONIAN — 


14) 


exci 


_couchel_F0 




5.0 


15) 


exci 


_couchel_F2 




13.1769757147 


16) 


exci 


_couchel_F4 




8.299507532 


17) 


exci 


_couche0_l_F0 


5.5 


18) 


exci 


_coucheO_l_F2 


7.6574518 


19) 


exci 


_couche0_l_Gl 


5.77390099368 


20) 


exci 


_coucheO_l_G3 


3.28715525784 


21) 


exci 


_S0_0 




6.845918392 


22) 


exci 


_S0_1 




0.066403136 


23) 


exci 


_Sop_Zero 




le-05 


24) 


exci 


_Sop_Mimis 




0.0 


25) 


exci 


_Sop_Plus 




0.0 


26) 


exci 


.counterDL 
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CALCULATION PARAMETERS — 
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27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46' 
47 
48 
49 
50 
51 
52 



reduc_l 

reduc_0_l 

alll 

E1213 

all2 

shift 

npunt i 

dxleft 

dxright 

temp 

erange 

tolef act 

shif t_invert 

nsearchedeigen 

NstepsTridiag 

Vs 

Vp 

vco 

VC1 

DREF 

ALPHAVC 

ALPHAVSP 

BONDS 

f actorhopexci 
f acts_hop 



case 



./ 

0.8 
0.8 
0.1 
700 
0.1 




500 

-0.1 

0.1 



0.009 
0.1 
le-06 




10 

250 

2.0 

1.0 

0.2 

0.0 

1.0 

-3.0 

-3.0 



[[-1.0, 0, 0], [1.0, 0, 0], [0, -1.0, 0], [0, 1.0, 0], [0, 0, -1.0], [0, 0, 1.0]] 



1.0 

None 



select a value to change , to stop, filename to read values 



To change a parameter, one enters the corresponding number and then the 
new value. If, instead of a number, one enters a file- name like "paramfile" of a 
previously saved parameter file (the quotes are important), then that file will 
be loaded. Such a file can be edited with any text editor. 

All energies are given in eV and all distances in Angstrom. The param- 
eters can be divided in three blocks. The first two are atomic Hamiltonian 
parameters for the base and excited configurations respectively. The first seven 
atomic parameters are Slater integrals : three (F0,F2,F4) for the d-d interaction 
(couchef), and four for the interaction between the 2p shell and the 3d one ( 
coucheCLI). The parameter SO n is the spin-orbit interaction for the n th shell 
( in this example is2p and I means 3d . The one-particle energy of the or- 
bitals is not given in input. Therefore the absolute energy scale of the spectra 
is arbitrary. 

The parameters SopJZero , Sop-Minus, Sop_Plus arc the three components 
of an external exchange field acting on the 3d shell. They multiply the three 
components of the 3d spin operator S z , S-i, S+i. These factors can be real or 
complex. Finally the parameter counterDL is an energy which multiplies the 
number of electrons on the Oxygen orbitals. 

The block called CALCULATION PARAMETERS contains other interest- 
ing parameters. We start discussing the last ten : Vs, Vp, VCO, VC1, DREF, 
ALPHAVC , ALPHAVSP, BONDS, factorhopexci, factsJiop. These parameters 
are relevant for the Hamiltonian. They describe hybridisation and crystal field. 

The hybridisation of the 3d shell with the Oxygen 2p orbitals is described 
by the Slater-Koster parameters Vs and Vp for a = 3z 2 — r 2 and ir = xz, yz 
orbitals, where z is aligned along the bond direction. The hybridisation term 
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is summed over all the bonds given by the BONDS variable. The Slater-Koster 
parameters are rescaled as {Rbondl ' DREF) ALPHAVSP where Rbond is the bond 
length. 

The parameters VCO and VC1 work in a similar way and describe the 
crystal field. They arc the energy shifts for a and 7r orbitals. respectively, 
assuming that z is aligned along the bond direction. The scaling factor is 
(R bond /DREF) ALPHAVC . 

The other parameters are described here : 

P) case : the directory where the Hilbert space has been generated by the 
scriviFiles command. 

P) reduc_l : the usual Slater integral reduction factor for 3d shell 

P) reducJ)A : reduction factor for 2p — 3d Slater integrals. 

P) alll : Lorentzian broadening before E1213 

P) E1213 : an energy between L2 and L3. 

P) all2 : broadening after E1213 

P) shift : an energy shift. 

P) npunti : number of points in the spectrum. 

P) dxleft : the spectrum is calculated from dxlcft.... 

P) dxright : .... to dxright 

P) temp : when several ground state eigenvectors are calculated they are Boltz- 
mann averaged with a Tempcrature=temp. 

P) erange : the lowest energy ground-states are calculated which are within 
an energy range= erange. The smaller the erange, the faster will be the 
calculation since less ground states are considered. 

P) tolefact : The ground states having Boltzmanian weight less than tolcfact 
are neglected 

P) shift_invert : not used. 

P) nsearchedeigen : The Lanczos diagonalisation of the ground state Hamilto- 
nian searches for nsearchedeigen eigenvectors. ( the smaller this number the 
faster the calculation ) 

P) NstepsTridiag : dimension of the tridiagonalised matrix used for calculating 
the spectra. 
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When the program is started, the system parameters are initialised with 
default values. If two files named out36-base and out36-exci are found in the 
working directory, the Slater integrals and the spin-orbit-coupling are searched 
for in such files. These files are not mandatory. If they are not there you will 
have to input the entries by hand. 

The out36 files are the output as from the Cowan's Ren program. Hilbertxx 
comes with a GUI which allows to run Ren and generate the out36 file. To run 
the GUI, from the working directory : 

hilbertxx_directory/ cowan/cowan in36 

There is a short help for every RCN parameter. You can play with the 
parameters and create the out36 files that you need. 

The examples are already provided with the related out36 files, so you need 
to run RCN only for the cases you want to study. 

To run a simulation you must first create a directory with the Hamiltonian 
components in the Hilbert space. Let's call it HCD ( hamiltonian components 
directory ). You obtain this by the command scriviFiles . When you run 
../runthis script , and your working directory has subdirectory name datas , 
write the command : 

scriviFiles (4,pref ix="datas" , nfiopped=2) 

the first argument is the minimum occupation number for the 3d shell. Such 
command creates a Hilbert space for the base system and another for the excited 
system. The base space spans all the configurations having 4, 5 and 6 electrons 
on the 3d shell. The excited space spans those having 5,6 and 7 electron on 3d 
and 5 on the Mn 2p shell. The number of electrons on the Oxygen 2p orbitals 
can be either 10 or 9 or 8 and the total number of electrons is conserved. 

The program considers only those Oxygen orbitals that are obtained pro- 
jecting the 3d orbitals through the hopping operator. 

When the HCD has been populated with files created by the above command, 
you are ready to calculate a spectrum. The HCD needs to be created only once, 
and then you can play with parameters. 

In the example directory there is already a file with parameters which cor- 
respond to a case with strong hybridisation. Such a file is named paramn and 
can be loaded using the set(system) command. 

To calculate a spectrum : 

res=sy st em. Get Spectrum () 
and to plot the isotropic absorption 
Plot (Curve (res [0] , (res [1] +res [2] +res [3] ) . imag, Pen (Red) , "legend")) 

Several expectation values can be calculated with the following commands 
Es, S2s, L2s, SL2, occPs , Szs, Lzs= system. GetESLcounters () 
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Each variable Es, S2s, L2s, SL2, occPs , Szs, Lzs is a list of expectation 
values of a given operator. There is an expectation value for each calculated 
ground eigenvector. The operators are energy, S.S, L.L, 2S.L, the occupation 
of the ligand orbitals, S z , L z . The angular operators are restricted to the 3d 
shell. 

2.2 The RIXS examples class 

The directory hilbertxx/examples/exa_rixs/ contains the code to calculate the 
ls-3p RIXS. 

2.2.1 Mn3+ 

As in the previous example, you run the command 
. . /runthis script 

from the example directory hilbertxx/examples/exa_rixs/Mn3+. You get a sum- 
mary of the available commands by entering helpQ. You can calculate ls-3d ab- 
sorption spectra, as in the previous example, and RIXS. The absorption can be 
calculated either for the quadrupolar or for the dipolar interaction. The dipo- 
lar absorption can be calculated for centrosymmetric systems. To do this the 
program calculates a dipolar transition to a virtual 4p state which is projected 
through an hybridisation operator onto the Oxygen orbitals. The command to 
get the dipolar absorption is the same as for the previous example : 

res=system. GetSpectrumO 

The quadrupolar absorption can be calculated for a defined polarisation. 
You define the polarisation giving its 5 components on a L=2 basis. 

res=system.GetSpectrum( [fm2, fml,fO,fl, fp2 ]) 

where fm2, fml,fO,fl, fp2 are the five polarisation coefficients in the angular 
momentum representation. For example for xy polarisation [fm2, fml,fO,fl, fp2 
] = [ 1,0,0,0,-1 ] while for calculating x2y2 [fm2, fml,f0,fl, fp2 ] = [ 1,0,0,0,1 ]. 

The scriviFiles command has one more argument spinfixed . It defaults to 
zero ( no spin constraint ). If it is set to one, the Hilbcrt space is generated 
under the constraint of a fixed total spin S z . This has in general little effect on 
the absorption spectrum because the spin-orbit coupling is small in the 3d shell 
and the calculation is faster. 

The use of the set( system ) command is the same as in the previous example. 
The difference is that there are some more parameters for the final state ( for 
RIXS) and some more for the 4p-Oxygen hybridisation which is used to calculate 
the dipolar ls-3d transition. The latter parameters are Dips , Dipp, which are 
the Slater-Kostcr a and 7r parameters for 4p-2p hybridisation, and ALPHADIPO 
, which is the analogous of ALPHAVSP. 
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A parameter file is provided for the study case of Mn : "paramnH" The 
calculation must be run in the Hilbert space created with the following command 

scriviFiles(4, pref ix="datas" , nhopped=2, spinfixed=l ) 

The studied ion is in a non-centrosymmetric position and we can calculate both 
quadrupolar and dipolar absorption. The following commands 

resx2y2 = system. GetSpectrum( [ 1.0 , 0.0 ,0,0, 1.0 ] ) 
resyz = system. GetSpectrum( [ 0.0 , 1.0 , , 1.0 , ] ) 
resdip=system. GetSpectrumO 

allow to compute the absorption spectra for x 2 — y 2 , yz and dipolar polar- 
isation respectively. 

You can compare the polarisation dependence of the quadrupolar absorption 

Plot (Curve (resx2y2 [0] , resx2y2 [1] . imag, Pen (Red) , "x2y2"), 
Curve (resyz [0] , resyz [1] . imag, Pen() , "yz")) 

and you can plot a dipolar isotropic spectrum : 

Plot (Curve (resdip [0] , (resdip [1] +resdip [2] +resdip [3] ) . imag, Pen (Red) , "dipole")) 

Now you can calculate a RIXS spectrum : 

res= system. GetRIXSC polarisationIn= [0 . , 1.0,0.0, 1.0,0.0] ,polarisation0ut= [1 . , . 0] , ein=26.43, 
eoutl=630, eout2=790, dout=0.1, gammain=0 . 2 , gammaout= [ 0.5 , 20 , 1 . ]) 

where the energy is tuned to the first absorption peak. The RIXS calculation 
is performed considering only one ground state, the lowest one regardless of the 
temperature and erange parameter. 

2.3 The df examples class 

The directory hilbertxx/examples/exa_df/ contains the code to calculate dipolar 
d to / transitions. This example considers a crystal field on the f shell but not 
hybridisation. 

2.3.1 Ho 

This example is very similar to the pd case. The only difference is that there 
are three parameters for the crystal field and no hybridisation. 
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3 Description of the code 



The low level objects are coded in C++ and wrapped in Python. The description 
of the system and the manipulation of basic objects are done in Python. 

There are two levels of use of Hilbcrt++ : the developer level and the user 
level. 

At the user level one uses a command line interface which allows to manip- 
ulate the parameters of an already defined system. 

At the developer level one can create new systems by doing some scriptic 
programming in Python. 

The Hilbcrt space is spanned by a set of second quantisation base vectors: 

e = 44 . . .c+|0) 

The code represents a base vector by a C++ object eo. This object contains 
two chains of bits : eo.val and eo. signs. The i th bit of eo.val is equal to the 
occupancy of the i th one-particle state ( 1 or 0). The eo.sign chain of bits is 
used to keep track of fcrmionic statistics and is the integral modulus 2 of eo.val. 
If, for example, c.val = 00010010.... then c.signs = 00001110.... 

The creation and annihilation operators are represented under the form of 
one particle base vectors : they are represented by a base vector co whose eo.val 
has only one bit set to one: i.e. the bit corresponding to the particle state. A 
co creation operator acts on a base state in the following way : first the "AND" 
bitwise operation is applied to eo.val and eo.val. When the one particle state 
is already occupied in the vector eo the "AND" operator gives a non-zero bit 
string and the result is set to zero. Otherwise the result is a new vector reso 
multiplicatcd by a ±1 factor. The vector reso is composed by a reso.val which is 
obtained by the "OR" bitwise operation on eo.val and eo.val. The signs strings 
reso. signs is the result of the "XOR" operation on co. signs and eo. signs. The 
multiplicative factor is +1 if (eo.val AND eo. signs) = 0, otherwise it is —1 

Starting from these basic objects ( base vectors and creation/annihilation 
operators), the generic operators and vectors are constructed. An operator 
is in general a linear combination of creation/annihilation operators or their 
products. A vector is a linear combination of base vectors. 

The generation of a Hilbert space starts from a seed basis, which is a basis 
formed by one or a few base vectors, and a wanderer, i.e. an operator which, 
operating on the basis, creates new basis vectors. The wanderer is applied 
several times on the basis, making it grow until no new base vectors are found. 

The ground state space spans all the configurations having 4, 5 and 6 elec- 
trons on the 3d shell. The excited state one spans those having 5,6 and 7 electron 
on 3d and 5 on the Mn 2p shell. The number of electrons on the Oxygen 2p 
orbitals varies in order to conserve the total number of electrons. 

The number of Oxygen orbitals is in principle 6Nb where Nb is the number 
of bonds. As in the above model Hamiltonian the Oxygen orbitals arc degen- 
erated, one can arbitrarily chose a rotated basis for the Oxygen one-particle 
wavcf unctions. The basis that we choose is such that the first 10 basis vectors 



are obtained projecting the 3d space on the oxygen orbitals through the hopping 
operator and applying a Grahm-Schmidt orthonormalization. The remaining 
vectors span a space that is not related to this problem and are neglected. 

For an absorption study two Hilbcrt spaces are expanded, one for the ground 
configurations, and another for the excited ones. The different components of 
the Hamiltonian arc calculated separately and written in files , in the form of 
sparse matrices. 

This is done writing a Hamiltonian component ( kinetic energy, electron- 
electron interactions, spin-orbit coupling, etc.... ) as a generic operator. This 
operator is subsequently applied to every basis vector i of the considered Hilbert 
space. The result is a linear combination of a small number of basis vectors to 
which the vector i is connected through the operator. 

The sparse matrix, representing the operator, is a sequence of triples {j,i,Cji) 
where i and j are two connected basis vector indices and Cji is the matrix ele- 
ment. The total Hamiltonian is built as a linear combination of its components. 
The dipolar and quadrupolar operators connecting the Hilbcrt spaces between 
each other are represented as space matrices as well. 

To calculate absorption and RIXS spectra one needs to compute eigenvectors 
and the respective eigenvalues : 

HX n = \ n X n 



spectra 



inversion 



(x\ 5— H*> 

to — H + *7 

1 IX) 



ui — H + 27 

To do this, one just needs to apply the Lanczos algorithm and the conjugate- 
gradient method, which are based on the simple multiplication 

y = Hx 

We have implemented the Lanczos algorithm with thick restart from Kesheng 
Wu & Horst Simon [1]. The absorption is obtained finding first the ground 
eigenvectors X n via the Lanczos method. The vector DX n , where D is the 
dipolar ( or quadrupolar) operator is then calculated in the excited Hilbcrt 
space. This vector is taken as an initial vector at the zero-th step of the Lanczos 
tridiagonalisation procedure. A large enough number N of steps is performed to 
generate the diagonal on (0 < i < N) and off diagonal (3j (1 < i < N) elements. 
Te resonance amplitude is then given by the following continued fraction : 

1 



LU + 17 — D!Q — 



— Qi — 

The imaginary part of the above expression is proportional to the absorption. 
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The RIXS signal is calculated in a similar way and one takes at the first step 
of the tridiagonalisation procedure, the vector 



Dout — —\Di n X n ) 

oJiii — H + ij 

where and D out are the dipolar ( or quadrupolar ) operators for the incoming 
and outgoing photons, respectively. 

4 Details on the hybridisation components of 
the Hamiltonian 

We consider a metal ion surrounded by Oxygen atoms. The total Hamiltonian 
is : 



H — H ato + 

^ {ta,bds S 2_ r 2Ps + tTT.bid^Px + dp z py) + C.C.) + 
b 

e pJ2( p i p * + p t p y + p t p *) + 

b 

^(V atb d^ 2 _ r2 d 3i 2_ r 2 + V Vt b(d^ s diz + d~ s dyz)) (1) 
fa 

In this expression H ato is the atomic Hamiltonian. The sum ^ & runs over 
the metal-oxygen bonds b and the z axis is aligned along the bond direction. For 
d metals the hopping is expressed as a function of the Slater-Koster parameters 
to-, which are rescaled according to the bond length. For the same metals the 
electrostatic crystal field is described in terms of the parameter V a which is the 
energy shift of the 3z 2 — r 2 orbital, and of which is the energy shift of the 
xz and yz orbitals. The crystal field parameters are rescaled accordingly. The 
sum over the spin is omitted in the above formulae for conciseness. As to the 
df case there is one more the crystal field parameter : in total there are three 
parameters VCO, for z 3 , VC1 for (5z 2 — r 2 )x and (5z 2 — r 2 )y, and finally VC2 
for zxy and z(x 2 — y 2 ). 
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6 Final comment 



The code is provided not only as a binary, ready to use executable, but also with 
the sources. This because, analogously to what happens in research, the only 
interesting code is the one that has not yet been written. Having the source 
will hence allow you to better adapt it to your research topic. The supplied 
examples can nonetheless be very useful and many things can be learned working 
with the parameters. Like everybody else, the author does not know what he 
will be doing in the future : may be expanding the code in some way or doing 
something completely different. However if you have some interesting subject we 
can possibly discuss it together. The distribution does not contain yet examples 
with neighbouring metal ions like in [2]. Future versions will. 
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